home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / mpool.z / mpool
Encoding:
Text File  |  2002-10-03  |  8.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      MMMMPPPPOOOOOOOOLLLL((((3333))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((JJJJuuuunnnneeee 4444,,,, 1111999999993333))))           MMMMPPPPOOOOOOOOLLLL((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           mpool - shared memory buffer pool
  10.  
  11.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.           ####iiiinnnncccclllluuuuddddeeee <<<<ddddbbbb....hhhh>>>>
  13.           ####iiiinnnncccclllluuuuddddeeee <<<<mmmmppppoooooooollll....hhhh>>>>
  14.  
  15.           MMMMPPPPOOOOOOOOLLLL ****
  16.           mmmmppppoooooooollll____ooooppppeeeennnn ((((DDDDBBBBTTTT ****kkkkeeeeyyyy,,,, iiiinnnntttt ffffdddd,,,, ppppggggnnnnoooo____tttt ppppaaaaggggeeeessssiiiizzzzeeee,,,, ppppggggnnnnoooo____tttt mmmmaaaaxxxxccccaaaacccchhhheeee))));;;;
  17.  
  18.           vvvvooooiiiidddd
  19.           mmmmppppoooooooollll____ffffiiiilllltttteeeerrrr ((((MMMMPPPPOOOOOOOOLLLL ****mmmmpppp,,,, vvvvooooiiiidddd ((((****ppppggggiiiinnnn))))((((vvvvooooiiiidddd ****,,,, ppppggggnnnnoooo____tttt,,,, vvvvooooiiiidddd ****)))),,,,
  20.                vvvvooooiiiidddd ((((****ppppggggoooouuuutttt))))((((vvvvooooiiiidddd ****,,,, ppppggggnnnnoooo____tttt,,,, vvvvooooiiiidddd ****)))),,,, vvvvooooiiiidddd ****ppppggggccccooooooookkkkiiiieeee))));;;;
  21.  
  22.           vvvvooooiiiidddd ****
  23.           mmmmppppoooooooollll____nnnneeeewwww ((((MMMMPPPPOOOOOOOOLLLL ****mmmmpppp,,,, ppppggggnnnnoooo____tttt ****ppppggggnnnnooooaaaaddddddddrrrr))));;;;
  24.  
  25.           vvvvooooiiiidddd ****
  26.           mmmmppppoooooooollll____ggggeeeetttt ((((MMMMPPPPOOOOOOOOLLLL ****mmmmpppp,,,, ppppggggnnnnoooo____tttt ppppggggnnnnoooo,,,, uuuu____iiiinnnntttt ffffllllaaaaggggssss))));;;;
  27.  
  28.           iiiinnnntttt
  29.           mmmmppppoooooooollll____ppppuuuutttt ((((MMMMPPPPOOOOOOOOLLLL ****mmmmpppp,,,, vvvvooooiiiidddd ****ppppggggaaaaddddddddrrrr,,,, uuuu____iiiinnnntttt ffffllllaaaaggggssss))));;;;
  30.  
  31.           iiiinnnntttt
  32.           mmmmppppoooooooollll____ssssyyyynnnncccc ((((MMMMPPPPOOOOOOOOLLLL ****mmmmpppp))));;;;
  33.  
  34.           iiiinnnntttt
  35.           mmmmppppoooooooollll____cccclllloooosssseeee ((((MMMMPPPPOOOOOOOOLLLL ****mmmmpppp))));;;;
  36.  
  37.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  38.           _M_p_o_o_l is the library interface intended to provide page
  39.           oriented buffer management of files.  The buffers may be
  40.           shared between processes.
  41.  
  42.           The function _m_p_o_o_l__o_p_e_n initializes a memory pool.  The _k_e_y
  43.           argument is the byte string used to negotiate between
  44.           multiple processes wishing to share buffers.  If the file
  45.           buffers are mapped in shared memory, all processes using the
  46.           same key will share the buffers.  If _k_e_y is NULL, the
  47.           buffers are mapped into private memory.  The _f_d argument is
  48.           a file descriptor for the underlying file, which must be
  49.           seekable.  If _k_e_y is non-NULL and matches a file already
  50.           being mapped, the _f_d argument is ignored.
  51.  
  52.           The _p_a_g_e_s_i_z_e argument is the size, in bytes, of the pages
  53.           into which the file is broken up.  The _m_a_x_c_a_c_h_e argument is
  54.           the maximum number of pages from the underlying file to
  55.           cache at any one time.  This value is not relative to the
  56.           number of processes which share a file's buffers, but will
  57.           be the largest value specified by any of the processes
  58.           sharing the file.
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 4/30/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      MMMMPPPPOOOOOOOOLLLL((((3333))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((JJJJuuuunnnneeee 4444,,,, 1111999999993333))))           MMMMPPPPOOOOOOOOLLLL((((3333))))
  71.  
  72.  
  73.  
  74.           The _m_p_o_o_l__f_i_l_t_e_r function is intended to make transparent
  75.           input and output processing of the pages possible.  If the
  76.           _p_g_i_n function is specified, it is called each time a buffer
  77.           is read into the memory pool from the backing file.  If the
  78.           _p_g_o_u_t function is specified, it is called each time a buffer
  79.           is written into the backing file.  Both functions are are
  80.           called with the _p_g_c_o_o_k_i_e pointer, the page number and a
  81.           pointer to the page to being read or written.
  82.  
  83.           The function _m_p_o_o_l__n_e_w takes an MPOOL pointer and an address
  84.           as arguments.  If a new page can be allocated, a pointer to
  85.           the page is returned and the page number is stored into the
  86.           _p_g_n_o_a_d_d_r address.  Otherwise, NULL is returned and errno is
  87.           set.
  88.  
  89.           The function _m_p_o_o_l__g_e_t takes a MPOOL pointer and a page
  90.           number as arguments.  If the page exists, a pointer to the
  91.           page is returned.  Otherwise, NULL is returned and errno is
  92.           set.  The flags parameter is not currently used.
  93.  
  94.           The function _m_p_o_o_l__p_u_t unpins the page referenced by _p_g_a_d_d_r.
  95.           _P_g_a_d_d_r must be an address previously returned by _m_p_o_o_l__g_e_t
  96.           or _m_p_o_o_l__n_e_w.  The flag value is specified by _o_r'ing any of
  97.           the following values:
  98.  
  99.           MPOOL_DIRTY
  100.                The page has been modified and needs to be written to
  101.                the backing file.
  102.  
  103.           _M_p_o_o_l__p_u_t returns 0 on success and -1 if an error occurs.
  104.  
  105.           The function _m_p_o_o_l__s_y_n_c writes all modified pages associated
  106.           with the MPOOL pointer to the backing file.  _M_p_o_o_l__s_y_n_c
  107.           returns 0 on success and -1 if an error occurs.
  108.  
  109.           The _m_p_o_o_l__c_l_o_s_e function free's up any allocated memory
  110.           associated with the memory pool cookie.  Modified pages are
  111.           nnnnooootttt written to the backing file.  _M_p_o_o_l__c_l_o_s_e returns 0 on
  112.           success and -1 if an error occurs.
  113.  
  114.      EEEERRRRRRRROOOORRRRSSSS
  115.           The _m_p_o_o_l__o_p_e_n function may fail and set _e_r_r_n_o for any of
  116.           the errors specified for the library routine _m_a_l_l_o_c(3).
  117.  
  118.           The _m_p_o_o_l__g_e_t function may fail and set _e_r_r_n_o for the
  119.           following:
  120.  
  121.           [EINVAL]       The requested record doesn't exist.
  122.  
  123.           The _m_p_o_o_l__n_e_w and _m_p_o_o_l__g_e_t functions may fail and set _e_r_r_n_o
  124.           for any of the errors specified for the library routines
  125.           _r_e_a_d(2), _w_r_i_t_e(2), and _m_a_l_l_o_c(3).
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 4/30/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      MMMMPPPPOOOOOOOOLLLL((((3333))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((JJJJuuuunnnneeee 4444,,,, 1111999999993333))))           MMMMPPPPOOOOOOOOLLLL((((3333))))
  137.  
  138.  
  139.  
  140.           The _m_p_o_o_l__s_y_n_c function may fail and set _e_r_r_n_o for any of
  141.           the errors specified for the library routine _w_r_i_t_e(2).
  142.  
  143.           The _m_p_o_o_l__c_l_o_s_e function may fail and set _e_r_r_n_o for any of
  144.           the errors specified for the library routine _f_r_e_e(3).
  145.  
  146.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  147.           _d_b_o_p_e_n(3), _b_t_r_e_e(3), _h_a_s_h(3), _r_e_c_n_o(3)
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 4/30/98)
  196.  
  197.  
  198.  
  199.